feat(api): support /v1/convert/source/batch endpoint#545
Merged
edeandrea merged 1 commit intoJun 15, 2026
Conversation
Add batch document conversion support for the new endpoint introduced in docling-serve v1.22.0. The batch endpoint processes multiple document sources asynchronously, returning a task ID for tracking progress. New types: - BatchConvertDocumentRequest: request model with sources, target, options, and optional webhook callbacks - CallbackSpec: webhook callback specification for progress notifications - Jackson2/3ValidationErrorDetailListDeserializer: handle server 422 responses where detail is a string instead of a list API changes: - DoclingServeConvertApi: add convertSourceBatch() and convertSourceBatchAsync() methods - S3Source: add maxNumElements field for capping objects in batch mode - ValidationError: fix deserialization when detail is a plain string Closes docling-project#540 Signed-off-by: Eric Deandrea <edeandrea@gmail.com> Signed-off-by: Eric Deandrea <eric.deandrea@ibm.com>
Contributor
There was a problem hiding this comment.
Pull request overview
This PR adds client + API-model support for docling-serve’s /v1/convert/source/batch endpoint (introduced in docling-serve v1.22.0), including request models for batch sources/targets/callbacks, client operations for submitting and auto-polling batch conversions, and improved ValidationError deserialization when the server returns detail as a plain string.
Changes:
- Add
BatchConvertDocumentRequestandCallbackSpecmodels and exposeconvertSourceBatch()/convertSourceBatchAsync()onDoclingServeConvertApi. - Implement batch convert operations in the serve client and add WireMock tests for sync/async batch flows (including S3 + callbacks).
- Fix validation error parsing to accept
detailas either a list of objects or a string (Jackson 2 + Jackson 3).
Reviewed changes
Copilot reviewed 11 out of 11 changed files in this pull request and generated 4 comments.
Show a summary per file
| File | Description |
|---|---|
| docs/src/doc/docs/whats-new.md | Documents new batch conversion API support and related request types/fields. |
| docling-serve/docling-serve-client/src/test/java/ai/docling/serve/client/AbstractDoclingServeClientTests.java | Adds WireMock tests for batch convert (sync/async), S3, callbacks, and null request validation. |
| docling-serve/docling-serve-client/src/main/java/ai/docling/serve/client/operations/ConvertOperations.java | Implements /v1/convert/source/batch submission + auto-polling variant. |
| docling-serve/docling-serve-client/src/main/java/ai/docling/serve/client/DoclingServeClient.java | Enhances 422 handling to surface validation detail messages in thrown exceptions. |
| docling-serve/docling-serve-api/src/main/java/ai/docling/serve/api/validation/ValidationError.java | Adds Jackson2/Jackson3 custom deserializers for detail field. |
| docling-serve/docling-serve-api/src/main/java/ai/docling/serve/api/serialization/Jackson3ValidationErrorDetailListDeserializer.java | New Jackson 3 deserializer for ValidationError.detail. |
| docling-serve/docling-serve-api/src/main/java/ai/docling/serve/api/serialization/Jackson2ValidationErrorDetailListDeserializer.java | New Jackson 2 deserializer for ValidationError.detail. |
| docling-serve/docling-serve-api/src/main/java/ai/docling/serve/api/DoclingServeConvertApi.java | Adds new batch convert API methods. |
| docling-serve/docling-serve-api/src/main/java/ai/docling/serve/api/convert/request/source/S3Source.java | Adds maxNumElements field for limiting objects read from S3 in batch mode. |
| docling-serve/docling-serve-api/src/main/java/ai/docling/serve/api/convert/request/CallbackSpec.java | New webhook callback specification model. |
| docling-serve/docling-serve-api/src/main/java/ai/docling/serve/api/convert/request/BatchConvertDocumentRequest.java | New batch conversion request model (sources/target/options/callbacks). |
:java_duke: JaCoCo coverage report
|
|
||||||||||||||
|
HTML test reports are available as workflow artifacts (zipped HTML). • Download: Artifacts for this run |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
/v1/convert/source/batchendpoint introduced in docling-serve v1.22.0BatchConvertDocumentRequestmodel withsources,target,options, and optional webhookcallbacksCallbackSpecclass for webhook progress notificationsconvertSourceBatch()(sync) andconvertSourceBatchAsync()(auto-polling) methods onDoclingServeConvertApimaxNumElementsfield toS3Sourcefor capping objects in batch modeValidationErrordeserialization when server returnsdetailas a plain string instead of a listTest plan
maxNumElementsserialization)./gradlew buildpassesCloses #540